61. Creating DSC Class-Based Resources

Note

The below information is extensively based in information taken from the PowerShell® Notes for Professionals book. I plan to extend this information based on my day to day usage of the language.

Starting with PowerShell version 5.0, you can use PowerShell class definitions to create Desired State Configuration (DSC) Resources.

To aid in building DSC Resource, there's a [DscResource()] attribute that's applied to the class definition, and a [DscProperty()] resource to designate properties as configurable by the DSC Resource user.

61.1: Create a DSC Resource Skeleton Class

1
2
3
[DscResource()]
class File {
}

This example demonstrates how to build the outer of a PowerShell class, that declares a DSC Resource. You still need to fill in the contents of the class definition.

61.2: DSC Resource Skeleton with Key Property

1
2
3
4
5
[DscResource()]
class Ticket {
  [DscProperty(Key)]
  [string] $TicketId
}

A DSC Resource must declare at least one key property. The key property is what uniquely identifies the resource from other resources. For example, let's say that you're building a DSC Resource that represents a ticket in a ticketing system. Each ticket would be uniquely represented with a ticket ID.

Each property that will be exposed to the user of the DSC Resource must be decorated with the [DscProperty()] attribute. This attributes accepts a key parameter, to indicate that the property is a key attribute for the DSC Resource.

61.3: DSC Resource with Mandatory Property

1
2
3
4
5
6
7
8
[DscResource()]
class Ticket {
  [DscProperty(Key)]
  [string] $TicketId

  [DscProperty(Mandatory)]
  [string] $Subject
}

When building a DSC Resource, you'll often find that not every single property should be mandatory. However, there are some core properties that you'll want to ensure are configured by the user of the DSC Resource. You use the Mandatory parameter of the [DscResource()] attribute to declare a property as required by the DSC Resource's user.

In the example above, we've added a Subject property to a Ticket resource, that represents a unique ticket in a ticketing system, and designated it as a Mandatory property.

61.4: DSC Resource with Required Methods

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[DscResource()]
class Ticket {
  [DscProperty(Key)]
  [string] $TicketId
  # The subject line of the ticket
  [DscProperty(Mandatory)]
  [string] $Subject
  # Get / Set if ticket should be open or closed
  [DscProperty(Mandatory)]
  [string] $TicketState
  [void] Set() {
    # Create or update the resource
  } [
  Ticket] Get() {
    # Return the resource's current state as an object
    $TicketState = [Ticket]::new()
    return $TicketState
  } [
  bool] Test() {
    # Return $true if desired state is met
    # Return $false if desired state is not met
    return $false
  }
}

This is a complete DSC Resource that demonstrates all of the core requirements to build a valid resource. The method implementations are not complete, but are provided with the intention of showing the basic structure.